EnigmA Amiga Run 1996 March

home *** CD-ROM | disk | FTP | other *** search

/ EnigmA Amiga Run 1996 March / EnigmA AMIGA RUN 05 (1996)(G.R. Edizioni)(IT)[!][issue 1996-03][Skylink CD IV].iso / earcd / util2 / fxslnks5.lha / fixslinks / ls.doc < prev next >

Wrap

Text File | 1992-10-26 | 24KB | 636 lines

LS 4.7ljr USER DOCUMENTATION Mon Oct 26 01:31:10 1992 IMPORTANT NOTE: LS 4.7ljr is compatible with Amiga OS Release 2.04 (and later) ONLY! Use version 4.4ljr or before if you haven't upgraded to 2.04 yet. Due to library version differences and bugs, this software will not work with pre-release versions of 2.0 (basically anything below 2.04). LS 4.7ljr will report ``ls: Need AmigaOS Release 2.04'' if it doesn't think that you have the correct version of the OS installed. The change to 2.04 ONLY was done for various reasons (ranked from most to least important): 1) More robust, powerful and consistent pattern matching. 2) More robust and consistent date handling. 3) 2.0 style (local) environment variables. 4) Author's desire to `convince' people to upgrade to 2.04. 5) Smaller binary size (due to use of ROM library routines). Of course all the new features help offset this saving... :-) ----------------------------------------------------------------------- LS 4.7ljr - A versatile Amiga directory listing utility. This software is Copyright © 1989, 1990, 1991, 1992 Loren J. Rittle. This software is Copyright for the sole purpose of protecting the fact that this is indeed free software. This software is wholly based upon Justin V. McCormick's PD LS ``V3.1 July 29, 1989'' with enhancements and bug fixes by the copyright holder, Loren J. Rittle. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. The word free above refers to freedom of software not cost of software. Learn about software patents. Learn about interface copyrights. Learn why you as a user should abhor software patents and interface copyrights in their current (and becoming) form. I can be reached at the following address: Loren J. Rittle 1008 Landing Rd. Naperville, IL 60540 (708) 420-7942 EMail: rittle@comm.mot.com and as 'Loren Rittle' on the MicroTech BBS (708) 851-3929 Original Notices by Justin: /* * This program is placed in the public domain with the * understanding that the author makes no claims or guarantees with * regard to its suitability for any given application, and that * the author assumes no responsibility for damages incurred by its * usage. Any resemblance of this program to any other program, * either living or dead, is purely coincidental. * * Feel free to borrow this code and make millions of dollars * from its sale or commercial use, but please give credit where * credit is due. * * Please do not send me money or stolen software! I enjoy mail, * phone calls, and legitimate software contributions of all kinds. * * Thanks for your encouragement and support, * Justin V. McCormick * * Justin V. McCormick can be reached via: * * BIX: jmccormick * PLINK: JVM * * PHONE: 303-290-8429 * * USMAIL: 8330 E. Quincy Ave. * Bldg. C, #312 * Denver CO, 80237 */ Synopsis: --------- Features intelligent columnar listing, versatile sort options, UNIX-style pattern matching, recursive subdirectory listing, customized output formatting and much more! People who like the UNIX ls should feel right at home. LS Version 4.5ljr, Sun Dec 29 22:23:52 1991 Usage: ls [-h?acdeklnrst1ADFHIMNOPRTXY <args>] [path] ... a List all entries A Display entries across line c Show filenotes D Show dirs last d About dirs F <format> Format output e Sort by extension H No headings and subtotals k No ANSI display codes I <pattern> Ignore pattern l Long listing M Mixed output files and dirs n No sort N <date> Show newer than date r Reverse sort O <date> Show older than date s Sort by size P Show full pathnames t Sort by date R Recursive listing 1 Force one entry per line T Total all subtotals Y <high> Set output rows X <wide> Set output columns Installation: ------------- LS can be put in your C: directory where LIST and DIR are normally found. LS can be made resident in your s:user-startup (2.0 and later) or s:startup-sequence (1.3 and before), but you may need to set the pure bit on LS after dearchiving to prevent spurious warnings: protect c:ls +p Normal Shell users should add to s:user-startup (2.0 and later) or s:startup-sequence (1.3 and before): resident c:ls WShell users would want to add to s:Config-WShell: resi c:ls The Command Line: ----------------- All arguments are optional. The default action is to give a short columnar listing, sorted alphabetically, using the current directory. Alphabetizing is always case insensitive. You can group your options together in any order, like this: ls -tlr df0: Or you can have options specified independently: ls -t -l -r df0: '-' and '--' signal the end of options on the command line to allow filenames that begin with a dash to be specified: ls -l -- -l - long listing of a file called '-l'. Also, a non-option argument signals the end of options on the command line: ls -l df0: -R - long listing of df0: and then a long listing of a file called '-R'. However, if you specify several file or path names, the options will *not* (as opposed to version 3.1 by Justin) return to their default settings between paths. For example: ls -l df0: df1: - this will cause ls to print the long listing of df0: then the long listing of df1: Options: -------- There are many command options for LS. You can get a quick reference list of options by typing: LS -? or LS -h (this output is shown up in the Synopsis section) Here is the complete list and description of the options: a List all entries [LS usually skips those files which have their 'h' protection bit set or their file name's of the form .#? (Like unix ls), #?.bak or #?.info (Because I hate to see the damn things). With the -a option, LS will reveal all entries in a directory]. "(#?.(info|bak)|.#?)" is the default hide pattern. This can be changed by setting the ls_hidepattern local environment variable (see subsection entitled, ``Environment variables''). For example, the following issued in a shell (or added to a shell-startup command file): set ls_hidepattern ".#?", would cause Amiga ls to function as a normal unix ls. c Show filenotes, implies long listing. The placement and way filenotes are displayed can be modified by setting the ls_highlight0.on and ls_highlight0.off local environment variables (see subsection entitled, ``Environment variables'') and the format string (see subsection entitled, ``Formatted Output''). The default format string is "%p %5b %8s %d %n%w%C\\n". The %C sequence is the place the filenote will appear in the output if requested with the '-c' option. ls_highlight0.on defaults to "\n\x9b" "2m/* " and ls_highlight0.off defaults to " */\x9b" "22m". Thus all filenotes will appear on the line after the normal long listing entry (that \n means linefeed in case you don't know C style formatting). E. g. R(0);T(00.266) > ls -c ram:a -----rwed c 1 0 Sep 30 22:37 a /* this file is neat */ For example: R(0);T(00.000) > set ls_highlight0.on " /** " R(0);T(00.016) > set ls_highlight0.off " **/" R(0);T(00.000) > ls -c ram:a -----rwed c 1 0 Sep 30 22:37 a /* this file is neat */ d Show information about directory entries only (i.e. doesn't display the files in a directory). e Sort by extension. k Do not use ANSI escape codes in output (for colored text, hiding cursor and obtaining the size of the window). l Give long listing. n Do not sort entries before displaying. r Reverse sort direction. s Sort entries by size. t Sort entries by date. 1 Forces one entry per line of output. Useful when piping ls output to other programs. A Force listing to flow across a line instead of down a column. For example: Without -A option you might see: apple far zip blue ghost cars jacks But with the -A option you would see: apple blue cars far ghost jacks zip D Show directory entries last. F Format output (see below). Please see ALIASES/ for some example usages of this feature. H Do not print directory headings or subtotals. I <pattern> Ignore pattern. Do not show entries that match the given pattern. May be given multiple times on a command line (As per GNU ls). Please see the section entitled ``Wildcards'' for more details on the format of a pattern. In short, uses the standard Amiga OS Release 2.04 pattern matching style. M Mix directory and file entries together in final output list. N <date> Show entries that are newer than the given date. O <date> Show entries that are older than the given date. Currently a date must be formatted as follows: /* Standard "MMM DD HH:MM YYYY" 'ls' format */ "Dec 09 21:19 1991" or "Dec 9 21:19 1991" (two spaces or a ' 0' MUST be present before a single digit day of month.) OR /* Standard "DD-MMM-YY HH:MM:SS" AmigaDOS 'date' and internal format */ "08-Jan-92 18:35:38" I have ARexx scripts called todayls, weekls and monthls that use these features. Please see REXX/ for these macros. As I can't imagine anyone actually using these features in the raw, I can't see a good reason to provide a more general/standard date format... Finally, you will note that the date format is quite close to the standard 'ls' long listing date format (except the user is always required to list both the year and the hour:minute, instead of one or the other). P Print full pathnames for all entries, implies one entry per line. R Recursive listing, descend into subdirectories that matches pattern. T Print grand total of all entries. If LS cannot determine the current CLI window size, LS assumes the output is 77 columns by 23 rows. The following two options let you control the output page width and length of the short columnar listing: X <wide> Set short listing page width to the given number of columns. Y <high> Set short listing page length to the given number of rows. BTW, LS doesn't care what the number of rows in a window is anymore. -Y is obsolete, but left in LS for compatibility with past releases. LS needed the height of a window to support pagination (which was removed because it was a masive hack! :-). Actual method to determine horizontal size: The actual method for finding a horizontal size to use is as follows (in order checked): 1. -X <wide> (or -1 option) 2. size returned from the Windows Bounds Request. [NOTE: Step two is skipped if the output is not to an interactive file or if the suppress ANSI escape codes option ('-k') is given.] 3. 2.0 style (local) environment variables `console_width'. 4. Hard-coded 77. Formatted Output: ----------------- For customized output, there is a special option that expects a format rule as the next "option": F <format> Format output with <format>, with the following special symbols: %p Print the protection bits %d Print the date, "MMM DD YYYY" (if entry is over 180 days old) or "MMM DD HH:MM" (if a recent file). %b Print the number of filesystem blocks used by this entry. %s Print the number of bytes used by this entry. %n Print the name of the entry. %S<arg1> Print the `time to upload' for this entry. <arg1> is the characters per second transmitted. Default, if not listed, is 230 cps which appears to be a good value for ZModem over a 2400 baud modem. %h Print the `hex file size' for this entry. %C Print filenote comment if present and requested with '-c'. Filenote comment will have the highlight entry 0 applied to it (see comments given in section describing '-c' option) before printing. In general, highlighting (ANSI color sequences, etc.) should never be placed in the format string directly as it will not be filtered out correctly when ls is given the '-k' option or when ls is printing to a non-interactive device. In %C's case, this is especially important and in fact nothing related to filenote formatting should be included because not all files have filenotes and in any event they are not always printed. %% Print a percent symbol. \n Print a linefeed. \t Print a tab. \" Print a double quote ("). \\ Print a backslash symbol. The default format rule that LS uses for long listings looks like this: -F "%p %5b %8s %d %n%w%C\n" Any of the format options that begin with the '%' symbol can have an optional pad count that lets you specify how many columns to use. For example: -F "%40n\n" would print each entry name right justified in a field of 40 columns. You can use this feature of LS to help create simple batch command files. For example, look at this command: LS -PF "copy %n RAM:\n" df0:#?.h This tells LS to perform a listing using full pathnames with a special format, matching only filenames that end with ".h" in directory df0:. Suppose df0: has the following files in it: joe.h fred.h pete.h ted.h Our example LS command would result in the following list of commands: copy df0:fred.h RAM: copy df0:joe.h RAM: copy df0:pete.h RAM: copy df0:ted.h RAM: We could create a script file from this by redirecting the output of LS to a temporary file: LS >ram:templist -PF "copy %n RAM:\n" df0:#?.h EXECUTE ram:templist ;Do the script DELETE ram:templist ;Delete it WShell 2.0 users could say the following to perform the same operation and avoid the use of a temporary file (and a bit of typing :-): ls -PF "copy %n RAM:\n" df0:#?.h | stdin User Customization of the Short Listing: ---------------------------------------- Above, user customization of the long format is discussed. Now we turn our attention to look at user customization of the short listing. LS implements user definable highlighting to entry types in the short listing. What does that mean in plain English? In past versions of LS, the default was to color directory entries in the short listing, but keep plain file entries colored normally. If the output was to a non-interactive file (e.g. a pipe or a file on disk) or the '-k' options was given on the command line, then the default changed to appending a '/' to directory entries in the short listing. With the advent of Amiga OS Release 2.04, there are now many more types of entries that can appear on a filing system (a disk). A number is associated with each entry type, e.g.: -4 is associated with a FILE LINK (hard link) -3 " " " PLAIN FILE -2 - 0 " " " NOT USED CURRENTLY 1 " " " ROOT 2 " " " USER DIR 3 " " " SYMBOLIC LINK (soft link) 4 " " " DIR LINK (hard link) [Please note that C= currently recommends that users not use soft links.] By default, LS 4.7ljr highlights entries as follows: FILE LINK: boldface PLAIN FILE: plain everything NOT USED CURRENTLY (as of OS 2.04) and out of range: plain ROOT: secondary color USER DIR: secondary color SYMBOLIC LINK: italics DIR LINK: boldface, secondary color Users of LS can modify the highlighting to be applied to each and every file type by simply setting local environment variables. Users can set as many or as few of the highlighting strings as they want, but must always set the 'on' string for LS to look for a new 'off' string. These setting, as all local environment variables, are on a per shell basis. The names of the environment variables to set is generated by concatenating the string sequences given below: "ls_highlight" <number_of_filetype_to_set_for> ".on" "ls_highlight" <number_of_filetype_to_set_for> ".off" For example, ls_highlight3.on would be the prepend string related to directory entries. Likewise, ls_highlight3.off is the name of the append string related to directory entries. Entering set ls_highlight3.on "" set ls_highlight3.off "*e[2m/*e[22m" would tell LS to append a colored '/' after each directory entry in a short listing. LS will keep track of the number of printable characters in the highlight strings and continues to format columns properly. LS only supports embedded ANSI sequences that start with a CSI ('0x9b') or ESC ('0x1b') '[' and end with 'm'. These ANSI sequences handle everything from text style to text color (foreground to background). As a special exception, a filenote comment highlighting string (0), is set to "\n/* " (on) and " */" (off) if found to contain an ANSI sequence. Sample ANSI sequences (as used from shell): "*e1m" boldface "*e2m" faint (secondary color) "*e22m" normal color, not bold "*e3m" italic "*e23m" italic off "*e4m" underscore "*e24m" underscore off "*e7m" reversed "*e27m" reversed off "*e3<digit 0-7>m" character color "*e39m" default character color "*e4<digit 0-7>m" background color "*e49m" default background color "*e1;2m" boldface, faint (secondary color) "*e22m" normal color, not bold "*e1;34m" boldface, color 4 "*e22;39m" normal color, not bold For more information see: ``Amiga ROM Kernel Reference Manual: Devices'' 3rd Edition pages 69-71. If the output of LS is to a non-interactive file (e.g. a pipe or a file on disk) or the '-k' options was given on the command line, then the prepend ('on') and append ('off') strings are striped of ANSI sequences. The search only checks the first character of each string to see if it is either a CSI ('0x9b') or ESC ('0x1b'). If an ANSI sequence is detected, then *both* highlighting strings are set to "". Environment variables: ---------------------- Starting with LS 4.5ljr, LS uses the standard 2.0 style (local) environment variables and support routines. See HIGHLIGHT_SETS/ for some example usages. The following is a list of all the environment variables LS deals with: console_width (see subsection entitled, ``Actual method to determine horizontal size'') ls_highlight-4.on, ls_highlight-4.off, ls_highlight-3.on, ls_highlight-3.off ls_highlight-2.on, ls_highlight-2.off, ls_highlight-1.on, ls_highlight-1.off ls_highlight0.on, ls_highlight0.off, ls_highlight1.on, ls_highlight1.off ls_highlight2.on, ls_highlight2.off, ls_highlight3.on, ls_highlight3.off ls_highlight4.on, ls_highlight4.off (see section entitled, ``User Customization of the Short Listing''), ls_hidepattern (see '-a' option subsection) Note that LS doesn't require any environment variables to be set. The use of these environment variables is for advanced users to take advantage of advanced features in LS. Also, note that for performance reasons, LS only refers to local environment variables. Wildcards: ---------- Starting with LS 4.5ljr, LS uses the standard Amiga OS Release 2.04 pattern matching style and support routines. If you want to continue to use a UNIX-style '*' in patterns, you should look into obtaining StarBurst or some similar utility that turns on the RNB_WILDSTAR bit in DOSBase->dl_Root->rn_Flags. This is one area that the standard Amiga OS is so far ahead of the unix standard that I had to switch! Wildcards may be used in file names and in the last level of a directory path name. The '#?' characters are used to match any number of characters, and a '?' matchs any single character. If you need to specify a pathname with spaces in it like "Wombat Soup", you need to put quotes around it. LS can process up to 100 separate pathname patterns in per command line. Please refer to page 7-31 of the Amiga Release 2 Manuals or page 255 of ``The AmigaDOS Manual 3rd Edition'' for more details. The following chart may help someone who already knows what regular expressions are (actually, with the examples anyone should understand): '?' - match a single character. E.G. a?b matches 'axb', 'ayb', 'atb', etc. '#' - matches the following expression 0 or more times. E.G. a#?b matches 'ab', 'axxb', 'ayyb', 'azitb', etc. a#b matches 'a', 'ab', 'abb', 'abbb', etc. '*' - synonym for '#?' if WILDSTAR option is turned on. NOT on by default. The WILDSTAR option is a system wide option, thus there is no switch in ls to control it. E.G. a*b matches 'axxb', 'ayyb', 'azitb', etc. '(' - start a new expression. '|' - separate items enclosed in '(' and ')'. ')' - end an expression. E.G. (cat|dog) matches 'cat' OR 'dog' only. #(cat|dog) matches 'cat', 'catcat', 'catdog', 'dogdogdog', etc. '~' - negate next expression. E.G. ~(cat|dog) matches anything but 'cat' OR 'dog'. E.G. ~c#? matches anything that doesn't start with a 'c'. '%' - matches 0 characters. (only considered special if other wildcards are present at same level, or in '(cat|%)' case). E.G. hi(cat|%)(dog|%) matches 'hi', 'hicat', 'hidog', 'hicatdog' only. '^' - listed in include file, but I don't know what it does... '[' - start character class. '-' - range (only special in '[]') ']' - end character class. E.G. [a-z]#? matches anything that starts with 'a' through 'z'. '<any char not listed above>' - an expression. As you have seen above, any plain character matches itself. LS uses the `NoCase' style pattern matching routines, thus an 'a' or 'A' will match an 'a' or 'A', etc. Here are some simple examples: LS -a df0:#?.info ; List all .info files in df0: LS -a df0:#?/#?.info ; List all dirs and .info files in df0: LS -a df0:l#?/#?.info ; List dirs that start with 'l' and .info files [NOTE: '-a' is needed because the current implementation of LS gives greater weight to patterns provided by '-I' and the builtin ignore patterns, namely #?.info, #?.bak and .#?, over explicitly mentioned patterns in all cases. This problem is being looked into. It seems that explicitly mentioned patterns should override particular ignore patterns in some cases. E.g. #?.info or source#?.info should override the builtin #?.info ignore pattern. BUT, #? should not override the builtin #?.info pattern. I currently believe the rule could be written as follows: If ignore pattern A covers explicitly mentioned pattern B, then ignore pattern A should be discarded while dealing with explicitly mentioned pattern B. The definition of cover is the same as when used in boolean algebra (function A is true whenever function B is true). Because of the computation time involved, I don't think that this problem will be addressed anytime soon. In fact, in general, proving that one pattern covers another may be NP complete or impossible. Since 99.99% of the time (or more :-) we could care less about the files mentioned in the default ignored list it makes no sense to slow down the program to cover this odd case. I just wanted the user to be informed of this behavior. -ljr] Also, wildcards are helpful when you are trying to avoid showing certain files with the "-I <pattern>" option. For instance: LS -I #?.o ; List current dir, do not show .o files. LS -I #?.o df0: ; Same as above but lists df0: instead. LS -I #?.o df0:c#? ; List entries that start with the letter "c" ; in df0:, but do not list .o files.